This software is distributed under the GNU public licence. The licence informations are included in the "COPYING" file enclosed in this package. You may NOT distribute individual parts of this package, but only the package as a whole including the "COPYING" file.
NOTE: The included pieces called "MoreFiles", "MoreCFMPatches" and other "More...." in the "lib" directory are pieces of Apple's MoreFiles and MoreIsBetter packages. Those are freely distributed source packages containing various pre-made tools, by Apple. The licence on those package is quite "light" and probably conflicts with the GPL. They are _NOT_ covered by BootX GPL, BootX licence covers only the directories others than "lib".
Thanks to all the people who helped me make this possible, Terry Greeniaus (the provider of the hack to get into supervisor mode), Paul Mackerras (original port of Linux to PCI PowerMacs), Kevin Avila (Infinite OS), Olivier Gutknecht (better graphics) and all other people I forgot to mention !
WARNING !
BootX and miBoot should be avoided on "newworld" type machines. Those machines are all the "colored" macs (iMac and later). Those machines should be booted via Open Firmware, using yaboot or an equivalent OF based bootloader. The only "newworld" machine that still requires BootX/miBoot for proper functionalities is the "Lombard" (101/bronze keyboard) PowerBook, at least until it's video driver is fixed.
Installation
･ BootX Itself
BootX is made of a system extension and a control-panel like application. The extension goes into the "Extensions" folder of the system folder, it contains all the necessary code for booting linux at early startup time. The Application goes wherever you want, it's default location is the "Control Panels" of your system folder.
･ The Linux kernel
BootX needs a plain uncompressed Linux kernel or a coff compressed kernel. Usually, you are expected to create a folder called "Linux Kernels" inside your system folder, and drop kernel files there. (*)
(*) In practice, BootX supports several behaviours, some for historical reasons, others for ease of distributions makers:
- The kernel can be named "vmlinux" and be placed at the root of the system folder, next to your MacOS "System" file. You can change the list of supported kernel names by changing the STR# resource in BootX. You can put whatever number of names you want here.
- The same as above, but it can be placed next to BootX itself (application only)
- A folder named "Linux Kernels" can be created and placed in the system folder. Any ELF32 or coff file in this folder will be recongnised as a possible kernel and added to BootX menu.
- The same as above, but the folder can be placed next to BootX (application only)
There is no support yet for loading the kernel from the ext2 partition. This is planed for a future release, but I really cannot say when this will happen...
･ The RamDisk (usually for booting your distribution installer)
The installation ramdisk must be named ramdisk.image.gz and be placed in the system folder too or next to BootX App (but in this later case, only the application will be able to use it).
When the ramdisk is available, BootX will enable the "Use RamDisk" checkbox. You can check this whenever you want to boot into the installer (typically the RedHat installer).
Since 1.2, bootx also supports "vmlinux.coff" kernels with embedded ramdisk (xcoff images with an initrd section). The ramdisk file can still be separate when using standalone kernels, but can now be specified from the options dialog.
･ Root device setup
Once you have Linux installed, you need to use a plain kernel without ramdisk or uncheck the "Use specified ramdisk" checkbox in the options dialog for the kernel to boot your newly installed system. In order for the kernel to locate it, you should also tell it on which disk and which partition on this disk it is located. The installer usually gives you this information, it looks like "/dev/hdxy" or "/dev/sdxy" where x is a letter (a,b,c...) and y a number. Look at the various Linux documentations and FAQs if you have trouble locating the root device.
Notes
The extension is named "･ BootX Extension" for it to load last of all "scri" files. "scri" files are loaded very early during the boot process, that's why we use that type, but we still want things like WorldScript to load before us, just in case...
For CD-based installers, you can put "Linux Kernels" folder, "ramdisk.image.gz" and also the "BootX Settings" prefs file next to the BootX App application on the CD. They will override the ones eventually present in the system folder.
Note about compressed kernels: Recent kernels have a new format for vmlinux.coff (zImage) which is not compatible with BootX. You need to provide bootx and miBoot with a coff image containing an "image" section and eventually a "initrd" section. I've added targets miboot.image and miboot.image.initrd to the kernel Makefiles for this purpose. They are build when doing "make zImage" along with the other zImage formats (vmlinux.coff & vmlinux.elf).
Operations
Just try it ;-) Some keybard shortcuts are available:
- Tab will switch the "defaultness" of OSes
- Return/Enter will choose the current default OS
- Escape or Cmd-Q gets always back to MacOS
- Cmd-S saves your current settings
- Cmd-O opens the options dialog.
In case you find a bug
Please e-mail me (bh40@calva.net), with "BootX" in the subject of your message. Please also provide as much infos as possible about the problem, including:
- Hardware (Macintosh model, installed memory, video board, ...)
- MacOS version
- BootX version, and which module (extension/application)
- Virtual memory on/off
- File sharing on/off
- linux kernel origin (where did you get it ? when ? version ? did you compile it ? which compiler ? ...)
- If you crash or get to MacsBug, please send me a MacsBug StdLog
Release notes
･ 1.2.2 - 24/4/2000
- Reverted to CodeWarrior Pro4. Something is wrong when building with Pro5, I still have to investigate. This fixes a hang that occurs occasionally just before entering the kernel.
･ 1.2.1 - 11/4/2000
- Fixed the slowdown problem that occured on some 603e based machines. Latest MkLinux changes still not included (sorry). I'll try to get those in asap.
･ 1.2 - 30/1/2000
- Merged with miBoot source. Latest MkLinux changes were NOT included in this version. They'll be in a later
release.
･ 1.2b3 - 30/11/1999
- Changed the IDE reset code, it should no longer hang the machine with some ATAPI devices.
- The code preventing MacOS from shutting down the sound chip on iMac and B&W G3 should now work
with MacOS 9.0
･ 1.2b2 - 15/11/1999
- Included Ludovic Ishiomin NuBus fixes (thanks !).
- Added code to reset IDE devices (works around the MacOS 9 IDE boot problem)
･ 1.2b1 - 2/10/1999
- Major reorganisation and cleanup of the low level booting stuff, various bux fixes and improvement merged from miBoot. This includes a longstanding bug where the last 4 bytes of the device tree were cut off, some fixes to the kernel ELF parsing code, fixes to the device-reset mecanism, and more.
We now have a better separation of boot-related functions and GUI. The same file boot.c now contains all the booting stuff shared between BootX and miBoot with preliminary support for non-file based pieces. All the GUI remains in BootX.c.
The INIT version is now compiled as 68k code without MacsBug symbols and with all optimisations set for size to avoid as much as possible the various boot-time memory allocation issues.
- BootX can now load compressed xcoff images and image with embedded ramdisk
- Moved some options to a separate dialog. You can now choose which ramdisk file to use if you don't include it with the kernel.
- Added an option for enabling/disabling the forced resolution switch (may cause compatibility troubles in some case). This functionality was added to force MacOS to configure it's saved video settings before booting Linux and is only necessary when using "no video driver" on machines which tends to boot in 640x480 by default.
- Added shutdown code for ATI Rage128 bus master. Todo: stop adaptec boards too.
- Made optional the horrible hack that forced a SCSI operation before boot to make sure the SCSI controller is not shutdown. I now have a kernel fix for that, and this hack could be risky in other circumstances.
- Added new debug code. To get the debug output, press the option key when BootX loads (either during extension load or when launching the application).
･ 1.1.3 - 6/8/1999
- Fixed a stupid bug introduced in 1.1.2 that caused the first kernel in the menu to be always choosen , whatever choice you actually made.
- The Linux Kernels folder can now be an alias an files inside it too.
･ 1.1.2 - 5/8/1999
- Fixes a problem where pending update events could still be in the queue when the dialog was dismissed, potentially causing crashes later during the boot process.
- Fixes a problem preventing the "Set G3 cache" option (for G3 acceleration cards) from working on some machines
- Implemented a hack to prevent disabling of the sound chip on the iMac and Blue G3s.
- Fixed potential problems with the Extension and HFS+
- Added code to properly setup screen resolution before booting Linux (thanks Charlie McLachlan)
- Some documentation updates
･ 1.1.1 - 21/5/1999
- Fixes a little problem when a "vmlinux" file next to bootx could be displayed twice in the menu
- BootX now disables itself when running inside SheepShaver
･ 1.1 - 19/5/1999
- Added a popup menu for choosing the kernel to boot from. The usual locations for kernel are still recongnized, but a new "Linux Kernels" folder can now be placed next to boox and/or in the system folder. Any file in this folder that is recognised as a valid ELF file will be displayed in the menu.
- Finally fixed a couple of old cosmetic bugs in the dialog's text fields
- G3 Cache option should now work better on pre-G3 machines. Requires appropriate kernel patch which should be included soon in the mainstream kernel release. (Check for "cpu" property in addition to "cpus").
- Some improvements to NuBus machines support. BootX now handle detection of the machine type (PDM, performa,
PowerBook) and set bits in the "architecture" field of the boot_infos.
- Updated a couple of obsolete statements in this file
- Included a fix for NuBus machines in the boostrap based on a sync/eieio fix in MkLinux kernel. I don't know if this can fix the problems booting some NuBus boxes, but it will do no harm so it's in.
･ 1.0.3b2 - 11/4/1999
- Improved new reset code. Should now work correctly with iMac USB, reset ATI mach64 bus master, etc...
- Some more code cleanups
- Preliminary support for NuBus PowerMacs so that kernel porting to those machines can begin. Currently, this is quite rough, it boots a performa I have here and a 6100. Still requires some work, especially regarding handling of the internal video of those machines. (video in DRAM).
On NuBus machine, the kernel is always loaded at 0x200000 physical (with this version). This will be changed to accomodate real physical memory ranges and video-in-DRAM in a later release. See BootX.h for more infos about parameters passed to the kernel.
- Removed simple trace stuff (mainly used for debugging the INIT). Will be replaced by some kind of log file.
･ 1.0.3b1 - 22/3/1999
- Added code for resetting some devices before relocating the kernel (especially devices doing DMA
to main memory). This fixes a crasher with Apple's UW controller, and may fix a couple of other issues
users had with bootx. Affected devices are the iMac USB controller (actually, PCI USB controllers should
be reset too), Apple's Symbios 53C875 board, and all DBDMA channels.
･ 1.0.2 - 10/3/1999
- Fixed a bug in the page re-ordering code.
- Updated a couple of comments here or there, added one or two things in the FAQ.
･ 1.0.2b4 - 17/2/1999
- Included the "GrabG3CacheSetting" tool for users of G3 upgrade cards. This tool will "capture" the current cache setting of MacOS when you launch it and store this setting in BootX prefs. Once you have done that, the "Set G3 Cache" checkbox will be available in BootX.
- Virtual Memory related fixes, Boostrap improvements.
- Moved error messages to STR#,ID 1000 resource to ease localisation
- This one should boot iMacs, but may require an appropriate kernel patch.
･ 1.0.2b3 - 15/2/1999
- Changes dramatically the way BootX enters the kernel. More details to come when I have time to update the tech. part of this document. The test kernel (and PEF loading) is dead, so if you want to use BootX for something else than Linux, do ELF32
- Add a missing HideCursor() to the 68k bootstrap to get rid of a ghost mouse cursor on some machines.
- Other misc fixes.
･ 1.0.2b1 - 25/12/1998
- BootX now resolves aliases when looking for files. This should work with every files used by BootX : prefs, kernel, ramdisk and MkLinux booter plugin. (I didn't test all of them however).
- Added some code to close and remove the MacOS video drivers before switching to linux. Tell me if that breaks your system.
- BootX now returns an additional field to the kernel, with the logical address of the framebuffer. The old one is now always a physical address. (This was broken if BootX had to switche your display to 8 bits, which should not happen unless you are in 1,2 or 4 bits, quite rare).
･ 1.0.1 - 22/12/1998
- Removed the 30 seconds limitation of the boot delay. You can now change this delay to a higher value by editing the STR# id 132 resource in BootX Extension.
･ 1.0 - 20/12/1998
- Fixes a refresh problem with the outline of the default button on pre-8.5 systems
- Added code to get an optional L2CR value (G3 L2 cache settings) from the prefs file. This value must be an "L2CR" type resource ID 0 stored in the prefs file. It should contains a long integer (4 bytes) containing the L2CR value. This resource will be filled by G3 upgrade card software or by a specific application not finished yet. The L2CR value is stored in the registry and made available to the kernel. Note that the patches for the kernel to retreive and apply this value are not yet in the main source tree at the time of this writing (2.1.131).
- BootX now ignores completely the root-device field when the ram disk is used to avoid confusion of the kernel.
1.0b7 - 23/11/1998
- Minor user interface fixes
- Changed a little bit virtual memory handling. You may get less -622 errors but this is not perfect at all yet.
･ 1.0b6 - 25/10/1998
- Minor improvements and fixes here or there (use a little bit less memory at startup, fixed error reporting in one or two cases, etc...)
- Added a workaround for a MESH problem on PowerBooks. BootX will try to do send an inquiry SCSI command to device at address 0. It doesn't matter if there is a device or not, the goal is to make sure that the MESH ship is correctly powered ON before we go to Linux. Ultimately, we should fix this in the kernel, but I still have to figure out the exact nature of the problem (setting the correct FCR bit in heathrow doesn't seem to be enough)
- Inside BootX Extension, there is a 'NOMT' resource which contains a single byte. Set it to 1 do disable code in BootX that tries to re-send disk mount events that occured when BootX dialog was displayed. Normally, we do that to avoid losing some external file system volumes (for example, if we don't do that, MountX may not automatically mount volumes on the desktop). However, since some people had problems with previous version that could have been caused by this code, I've added this workaround.
- Added a separate field for the root device. (Will add root=/dev/xxxx to the command line)
- BootX Extension (not the application) can now boot MkLinux ! The trick is to load MkLinux booter from within BootX and "fake" it's prefs file. See BootX source code for more infos about this hack. Enclosed is a little application "MakeMkPlugin" which will take the MkLinux Booter and build from it a new file named "MkLinux BootX Plugin" that resides in the Extensions folder. This file is a copy of the MkLinux booter with a diffent type/creator, preventing it from beeing loaded by MacOS at boot time (BootX will do it) and with a new icon (You may have to rebuild your desktop or use "Save A BNDL" on BootX Extension to see the new icon). It's also a little bit "patched" so that it works with the different name, but nothing terrific.
WARNING: Currently, if MkLinux boot fails, it will crash the machine. I'm planning on more patches to the MkLinux Booter to let it recover more gracefully, I just lack time.... So make sure you have your Mach Kernel file and correct lilo.conf available before trying to use MkLinux from BootX.
Note also that MkLinux booter will still use lilo.conf file for it's preferences (root device and command line args). This version of BootX will _NOT_ pass any of it's settings to MkLinux, edit lilo.conf manually for that.
･ 1.0b5 - 16/10/1998
- Changed again handling of VM locking, I hope this one works better with VM enabled on MacOS.
- A couple of source code cleanups
- Minor fixes to the low-level bootstrap
- New graphics and icons (thanks Ol.). You may have to rebuild your MacOS desktop or use Save A BNDL to see them.
･ 1.0b4 - 30/09/1998
- Added a call to DebuggerEnter() in the low-level boot. This makes MacOS think that we are a debugger and may help under some circumstances. Tell me if this changes is causing troubles.
- Added a couple of calls to the Power Manager to turn things on, make sure the processor is at max speed, etc...
- Locks kernel and device tree memory contiguously again.
- Disabled auto-switch to 8 bits is the screen is already greater to 8 bits depth. This change needs the new offb.c in the kernel to work in 16 and 32 bits in "No video driver mode".
- Added some processor cache flushing code, just in case... (should not be necessary because LockMemoryContiguous makes the area non-cachable, but I prefer doing it this way in case someone revers the make_resident again).
- Fixed PEF loading. Note that we still hold only 4k of TOC, this is really only intended for test kernel or quick tests.
･ 1.0b3 - 24/09/1998
- Fixed a stupid bug introduced in b2 that broke the boot delay. For an unknown reason, it looks like one line of code disappeared from the source just before the final build. Probably a bad move with the mouse. Sorry.
･ 1.0b2 - 24/09/1998
- The default boot delay of 10 seconds can now be changed by editing resource STR# ID 132. The first string in this resource is the boot delay in seconds.
･ 1.0b1 - 19/09/1998
- Preferences file support. Uses the same resource-based location mecanism used by the kernel and the ramdisk, except that instead of searching the system folder when the file is not found next to the application, It searches the Preferences folder.
- Implemented "No video driver" option (automatically adds "video=ofonly" to the command line)
- Changed a little bit the first drawing of the dialog
- Changed again the way bit depth is changed to 8 bits, using driver calls this time. It works fine from both the extension and the application on my machines.
- Added key shortcut "Cmd-S" for the "Save to prefs" button
- Several updates to this file
･ 1.0a8 - 18/09/1998
- Included Paul's new organisation of memory and ramdisk support.
- Added a RAM Disk check box that is enabled by default when a RAM Disk is present
- By default, BootX App will now first look for a ramdisk and a kernel next to the application, and if
it cannot be found, in the system folder. This should allow CD-based installers with this version
- RAM Disk lookup works like kernel lookup: you can have several names in a string resource
- Removed the count down in the application version
- Added a tempo after setting the color palette, just in case the driver takes a couple of refresh before realling changing the palette.
- The main 8 bits display now has the linux logo colors also.
･ 1.0a7 - 16/09/1998
- Added the current colormap to the boot-infos when the main device is 8 bits. This should be the last change to
the boot_infos structure. Since nothing was released yet, I didn't put this field at the end of the structure to preserve compatibility nor I changed the structure version number. Note that this offset directly points inside the registry copy and is expressed relative to the registry base like other pointers in the registry. It points to the node of the display device.
- BootX will now switch the main device to 8 bits to accomodate Linux offb.c which is limited to that depth.
- Any indexed video device will be set to the default 16 colors Linux colotable.
- Added a couple of comments to the source, moved all the display stuff from BootX itself to the low level booter
- the file BootX.h should now be indentical on MacOS and Linux.
- The registry pointer to the current display device is now found and stored in the boot_infos
･ 1.0a6 - 15/09/1998
- Fixed the kernel args (not correctly fetched from the dialog's editable text, "-v" was always passed to kernel
･ 1.0a5 - 15/09/1998
- The registry full pathnames generated by BootX now looks more like OF ones (using "/" instead of
":" as a separator). Unlike OF, we don't have the address appended to the name but this should not be an issue.
･ 1.0a4 - 14/09/1998
- Fixed the source archive (the binary was correct but not the source in the online archive).
- Fixed one or two minor things
･ 1.0a3 - 13/09/1998
- Fixed this readme file regarding changes in the boot_infos structure
- Makes sure that the block where the kernel is loaded is actually larger (by 512Kb) than the kernel itself. This is important since the Linux kernel will store things (like the device tree) just after itself at early boot time.
･ 1.0a2 - 13/09/1998
- Fixed a couple of bugs in the ELF loader (it could not work)
- Added some version informations to the boot_infos structure
- Fixed one or two things in the testkernel
･ 1.0a1 - 12/09/1998
- First release (also, this was my birthday ;-)
Technical infos
BootX will first prepare a big chunk of memory that contains the kernel image, the ramdisk, the boot infos (see below), a copy of the device tree (PCI machines only), and a couple more things. It will also load and lock several pieces of code:
- A 68k strap which takes control of MacOS shutdown, do some late setup operations (like walking all video drivers, getting resolutions, setting palettes, etc...)
- A PPC strap called from the previous one just before switching to supervisor (but after masking MacOS interrupts). This piece of code will shutdown some known devices that may still do DMA to main memory (Apple's NCR-based UW SCSI board, ATI mach64 accelerator, DBDMA channels, etc...). This piece of code also takes care of remapping PDM video to 1Mb on NuBus machines
- A PPC assembly boostrap called in PPC supervisor mode. This one will disable the MMU, copy kernel and ramdisk pages to the appropriate location (and re-order pages that were scattered by MacOS VM) and finally, enters the kernel.
Depending if you are running the application or extension version of BootX, things will differ a little bit. Both will install a special shutdown procedure in MacOS. The extension will just restart the machine immediately, the application will
send a shutdown AppleEvent to the finder. Note that the restart operation mail crash on some machines under MacOS 8.5. This is a known bug of this version of MacOS which is expected to be fixed by future release.
All offsets in the boot-info structure are relative to the beginning of this structure. All offsets within the device tree are relative to the beginning of the device tree. Note that the offset of the first node of the device tree is 4, not zero (we keep a fake long word at the beginning). This allow device-tree offset to never be NULL when actually pointing to something. Offsers that should _really_ be NULL contain a special value which is ... 0 (that mean that NULL in the device tree doesn't need relocation).
Note also that the device tree will be NON-PREPARED. That means that the "finish_device_tree" routine in 'prom.c' (linux kernel) will still be needed. No interpretation of the properties is done, this tree contains only the full pathnames, the raw properties, but no address_range or interrupt_info. Those fields will contain NULL, the kernel is responsible for filling them.
The kernel is passed the following arguments:
R3 = 'BooX' ($426F6F58)
R4 = Pointer to the boot_infos structure (see bellow)
R5 = NULL (used by quik as the pointer to OF prom)
The boot_infos structures is described in the bootx.h file of the distribution.
